#!/usr/bin/perl
use strict; use warnings;

use lib 'lib';

use Bigtop::TentMaker;

Bigtop::TentMaker::build_backend_list();

my $backends = Bigtop::TentMaker::get_backends();
my $output   = header() . chewy_center() . footer();

print $output;

sub chewy_center {
    my $retval = '';

    foreach my $type ( sort keys %{ $backends } ) {
        $retval .= "=head2 $type\n\n"
                .  "=over 4\n\n";;

        foreach my $backend ( sort keys %{ $backends->{ $type } } ) {
            $retval .= "=item $backend\n\n";

            my $hash = $backends->{ $type }{ $backend };

            $retval .= "This $type $backend makes the following:\n\n"
                    .  "=over 4\n\n";

            my @notes;
            OUTPUT_ITEM:
            foreach my $output_item ( @{ $hash->{ output } } ) {

                my ( $label, $descr ) = @{ $output_item };

                if ( $label eq 'note' ) {
                    push @notes, $descr;
                    next OUTPUT_ITEM;
                }

                $retval .= "=item $label\n\n$descr\n\n";

            }
            $retval .= "=back\n\n";

            if ( @notes ) {
                $retval .= "Notes:\n\n"
                        .  "=over 4\n\n";

                foreach my $note ( @notes ) {
                    $retval .= "=item *\n\n$note\n\n";
                }

                $retval .= "=back\n\n";
            }

            $retval .=
                "This backend understands these config block keywords:\n\n"
                . "=over 4\n\n";

            foreach my $statement ( @{ $hash->{ keywords } } ) {
                $retval .= "=item $statement->{ keyword }\n\n";

                if ( $statement->{ type } eq 'boolean' ) {
                    $retval .=
                        "This statement takes a boolean value use 0 or 1.\n\n";
                }

                $retval .= "$statement->{ descr }\n\n";
            }

            $retval .= "=back\n\n";
        }

        $retval .= "=back\n\n";
    }

    return $retval;
}

sub header {
    return <<"EO_HEADER";
=head1 NAME

Bigtop::Docs::AutoBackends - lists all backends and their config statements

=head1 Intro

Bigtop is a facade for a set of backends which do the actual generation.
Each generating backend lives in the Bigtop::Backend:: namespace.  Further,
each backend has a type or family.  For example, there are three generators
in the SQL family.  All of them live in the Bigtop::Backend::SQL:: namespace.
Finally, each backend is in a module, whose name completes the package name.
For example the PostgreSQL backend is Bigtop::Backend::SQL::Postgres.

Below are listes all the current Bigtop backends (at least the ones
that ship with Bigtop, your local system could have others).  In addition
to briefly describing what the backend is responsible for building, there
is also a description of all the keywords you can put in the backend's
config block to control its behavior.

All backends are listed in the Bigtop config block, which begins each
bigtop file.  That list controls what the user is allowed to build.
The order of appearance controls the order of generation when the user
chooses to build all, as in

    bigtop docs/app.bigtop all

A typical backend block looks like this:

    CGI Gantry { with_server 1; }

Here there is a backend type C<CGI>, a specific backend
C<Bigtop::Backend::CGI::Gantry> and a block with one statement:
C<with_server>.

That block goes in the config block at the top of the file:

    config {
        # config statements like 'engine' statements
        CGI Gantry { with_server 1; }
        # ... other backends
    }

Now that you know what backend blocks look like, and where to put them,
it's time for the L<Litany of Backends>.

=head1 Litany of Backends

Below is a subsection for each backend type.  Within the subsection is
a list of backends in that type family.

Note that the list below is in alphabetical order by type family,
but you almost always need to list an Init:: backend first.  They are
responsible for making the build directory among other things.

EO_HEADER
}

sub footer {
    my $now = scalar localtime;

    return <<"EO_FOOTER";
=head1 AUTHOR

The skip/backends script generated this file $now.
The script was written by Phil Crow E<lt>crow.phil\@gmail.comE<gt>.

=head1 COPYRIGHT and LICENSE

Copyright (C) 2007 by Phil Crow

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.

But keep in mind that it was generated.  Make modifications to the
generting script.

=cut
EO_FOOTER
}

=head1 NAME

backends - builds AutoBackends.pod from Bigtop::Keywords

=head1 SYNOPSIS

    skip/backends > lib/Bigtop/Docs/AutoBackends.pod

=head1 DESCRIPTION

This script pulls docs from the various Bigtop backends and spits
L<Bigtop::Docs::AutoBackends> to standard out.  Name that file
AutoBackends.pod.

=head1 AUTHOR

Phil Crow E<lt>crow.phil@gmail.comE<gt>

=head1 COPYRIGHT and LICENSE

Copyright (C) 2006-7 by Phil Crow

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.

=cut
